GitLab CI/CD for external repositories

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

GitLab CI/CD can be used with GitHub, Bitbucket Cloud, or any other Git server, though there are some limitations.

Instead of moving your entire project to GitLab, you can connect your external repository to get the benefits of GitLab CI/CD.

Connecting an external repository sets up repository mirroring and creates a lightweight project with issues, merge requests, wiki, and snippets disabled. These features can be re-enabled later.

Connect to an external repository

To connect to an external repository:

  1. On the left sidebar, at the top, select Create new () and New project/repository.
  2. Select Run CI/CD for external repository.
  3. Select GitHub or Repository by URL.
  4. Complete the fields.

If the Run CI/CD for external repository option is not available, the GitLab instance might not have any import sources configured. Ask an administrator for your instance to check the import sources configuration.

Pipelines for external pull requests

When using GitLab CI/CD with an external repository on GitHub, it’s possible to run a pipeline in the context of a Pull Request.

When you push changes to a remote branch in GitHub, GitLab CI/CD can run a pipeline for the branch. However, when you open or update a Pull Request for that branch you may want to:

  • Run extra jobs.
  • Not run specific jobs.

For example: 

always-run:
  script: echo 'this should always run'

on-pull-requests:
  script: echo 'this should run on pull requests'
  rules:
    - if: $CI_PIPELINE_SOURCE == "external_pull_request_event"

except-pull-requests:
  script: echo 'This should not run for pull requests, but runs in other cases.'
  rules:
    - if: $CI_PIPELINE_SOURCE == "external_pull_request_event"
      when: never
    - when: on_success

How it works

When a repository is imported from GitHub, GitLab subscribes to webhooks for push and pull_request events. Once a pull_request event is received, the Pull Request data is stored and kept as a reference. If the Pull Request has just been created, GitLab immediately creates a pipeline for the external pull request.

If changes are pushed to the branch referenced by the Pull Request and the Pull Request is still open, a pipeline for the external pull request is created.

GitLab CI/CD creates 2 pipelines in this case. One for the branch push and one for the external pull request.

After the Pull Request is closed, no pipelines are created for the external pull request, even if new changes are pushed to the same branch.

Additional predefined variables

By using pipelines for external pull requests, GitLab exposes additional predefined variables to the pipeline jobs.

The variable names are prefixed with CI_EXTERNAL_PULL_REQUEST_.

Limitations

This feature does not support:

Given that GitLab creates 2 pipelines, if changes are pushed to a remote branch that references an open Pull Request, both contribute to the status of the Pull Request via GitHub integration. If you want to exclusively run pipelines on external pull requests and not on branches you can add except: [branches] to the job specs. Read more.

Troubleshooting